home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Snippets / StandardGetFolder / StandardGetFolder.doc < prev    next >
Encoding:
Text File  |  1993-08-22  |  7.9 KB  |  158 lines  |  [TEXT/KAHL]
  1. /*************************************************************************************************
  2.  
  3. StandardGetFolder.doc -- Copyright Chris Larson 1993, All rights reserved.
  4.                        
  5. *************************************************************************************************/
  6.  
  7. Why Did I Do This?
  8. ------------------
  9.  
  10. In the course of working on a project, I happened to download the existing code samples
  11. for folder selection via the standard file package. After examining the code in each and
  12. discovering errors and/or omissions in all of them, I decided it was time to write my own.
  13. This package is the result of my efforts.
  14.  
  15. Features:
  16. ---------
  17.  
  18. o Internal error checking.
  19.  
  20.     Other packages performed no error checking. I use standard file’s internal error mechanism for
  21.   reporting errors when the user selects an invalid item (e.g. an alias which cannot be resolved).
  22.   The _only_ ways the StandardGetFolder function exits (barring an out of memory or resource not
  23.   found error -- which will both be reported if I detect them) is by the user selecting a valid
  24.   folder or by canceling -- just like calling StandardGetFile to select a file.
  25.  
  26. o Deals correctly with activate/update events for standard file dialogs and allows the application
  27.   to handle these events for its windows while standard file dialogs are active.
  28.   
  29.       The other packages do not even handle updating the standard file dialogs correctly. My routines
  30.   will update the dialogs correctly and provides a callback mechanism that allows the host program
  31.   to update its windows while the standard file dialogs are active.
  32.   
  33. o Complete support for Balloon Help.
  34.  
  35.     This was absent from all other packages. Customized help text is provided for every element
  36.   of the StandardGetFolder dialog.
  37.  
  38. o Easy to localize.
  39.  
  40.     Other packages had string literals within the code and other localization problems. I have
  41.   stored all string literals as resources and employed the International Utilities and Script
  42.   Manager where appropriate (as opposed to using strcmp() for example).
  43.  
  44. o Low network traffic when selecting folders from remote volumes.
  45.  
  46.     Other packages were querying the volume catalog almost every pass through the event loop,
  47.   resulting in a measurable amount of network activity when the user is idle. My routines are
  48.   designed to query for information only when necessary, thus dramatically reducing the network
  49.   activity when selecting a folder from a remote volume.
  50.  
  51. o Does not require the ANSI libraries.
  52.  
  53.     All work is done by calls to the toolbox, thus eliminating the need for use of the ANSI library.
  54.   Partly done for localization purposes and partly for space purposes, but in any case, no calls to
  55.   the ANSI library exist and only the MacTraps library is needed.
  56.  
  57. Problems:
  58. ---------
  59.  
  60. o Currently does not support selection of a folder for which only write privileges are
  61.   granted.
  62.   
  63.       This is a by-product of using standard file’s internal mechanisms for error checking. If
  64.   selection of write-only folders on remote volumes is important for users of this package,
  65.   I will work it into a future release.
  66.  
  67. How To Use:
  68. -----------
  69.  
  70. The StandardGetFolder.c file contains the source code for the entire package. It employs the three
  71. header files (SGF.h, StandardGetFolder.h, and PStrings.h). To use this package, simply add the file
  72. StandardGetFolder.c to your project, and #include the StandardGetFolder.h file in any source file
  73. of yours which references a StandardFolderReply record or the StandardGetFolder() call. The two
  74. other header files contain definitions required by the StandardGetFolder.c file -- they should not
  75. be required for use in any other portion of your code.
  76.  
  77. Refer to the file StandardGetFolder.h for a definition of the StandardFolderReply record and
  78. the StandardGetFolder prototype. A brief explanation follows.
  79.  
  80. The StandardFolderReply works much like a StandardFileReply: on exit, the sfGood field indicates
  81. whether the contained information is valid or not (invalid means the user canceled the operation).
  82. If sfGood is true, the directory ID and volume reference number of the selected directory are
  83. contained within the record. The contents are undefined if sfGood is false.
  84.  
  85. The returned directory ID and volume reference number _should_ be canonical (i.e. no working
  86. directory reference numbers) but when using them one should call FSMakeFSSpec(), or another
  87. appropriate routine, instead of simply filling in an FSSpec record directly.
  88.  
  89. As for the StandardGetFolder call, the parameters work as follows:
  90.  
  91.     prompt -- Str255 containing a string to be displayed atop the folder selection dialog box. Pass
  92.               in either NULL or the empty string if no prompt is desired.
  93.     
  94.     reply -- Points to the StandardFolderReply record to be used.
  95.     
  96.     windowProc -- Points to a routine for handling activate and update events for application
  97.                   windows. Pass NULL to disable this feature.
  98.  
  99. All extremely straightforward except for the windowProc. windowProc is a pointer to a function
  100. declared as follows:
  101.  
  102. void WindowProc (EventRecord* theEvent);
  103.  
  104. That is, a function which returns void and has a single parameter which is a pointer to the event
  105. to handle. This function _should_ only receive activate and update events and these _should_ only
  106. be for application windows (This is true of System 7.0.1 and 7.1) but the function should check
  107. to make sure before handling an event.
  108.  
  109. If this explanation is as clear as mud, refer to the included examples. The TestGetFolder.π
  110. sample is a bare-bones usage of the StandardGetFolder call to create an empty file within
  111. the selected directory. The bullseye.π sample is a modified version of the bullseye sample
  112. included with THINK C 6.0 which demonstrates the use of a windowProc to handle application
  113. windows (nothing is done to the selected folder in this sample -- it was used for cosmetic
  114. testing only). Please refer to these examples and to the liberally commented source code within
  115. the StandardGetFolder.c file if any questions remain.
  116.  
  117. If none of that clears it up, feel free to E-mail me at the given address below and I will attempt
  118. to help a little more.
  119.  
  120. As always, bug reports and comments are also welcome at the given E-mail address.
  121.  
  122. Other Info:
  123. -----------
  124.  
  125. Requirements:  This package was designed with System 7 facilities, thus it requires System 7 to
  126.                operate correctly.
  127.  
  128. Testing:  This package has been tested on a Macintosh IIci, LC, Plus, Classic, Centris 610, and
  129.           Powerbook 160, with Systems 7.1 and 7.0.1. It has been tested with SuperBoomerang 4.0.1
  130.           (well, the demo version anyway -- I don’t know anyone who has the full version) but not
  131.           with Norton Directory Assistance or any other such products.
  132.  
  133. Usage Rules:  This package (source code and compiled derivatives) may be used in any shareware
  134.               product (or other such stuff: freeware, beerware, postcardware, etc.) as long as you
  135.               mention me in your credits. This package is _not_ in the public domain and may _not_
  136.               be used in any public domain product in any fashion. (There is one exception to this
  137.               rule: the PStringCopy routine contained within the file "PStrings.h" was placed into
  138.               the public domain by Christopher Tate. This routine remains in the public domain
  139.               and may be used as such.) This package may not be used in commercial product without
  140.               the expressed, written consent of the author.
  141.  
  142. Legal Stuff:  This package is Copyright 1993 Chris Larson, all rights reserved (Again, except for
  143.               the PStringCopy routine). I have made a great effort to ensure that this package is
  144.               bug free but I make no warranty, either implied or stated, as to the functioning of
  145.               this package. By using this package, the user assumes all responsibility for damages
  146.               caused, either directly or indirectly, by its use.
  147.            
  148. Author:  Chris Larson
  149.          7009 Morton Court
  150.          Stockton, CA  95219
  151.          
  152.          Internet E-Mail (Preferred): cklarson@engr.ucdavis.edu
  153.  
  154. Version History:
  155. ----------------
  156.  
  157. 1.0 -- (8/93) Initial Release.
  158.